core/java/android/provider/DocumentsContract.java - fp2-dev/platform/frameworks/base - Gitiles

 /*
  * Copyright (C) 2013 The Android Open Source Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

 package android.provider;

 import static android.net.TrafficStats.KB_IN_BYTES;
 import static libcore.io.OsConstants.SEEK_SET;

 import android.content.ContentProviderClient;
 import android.content.ContentResolver;
 import android.content.Context;
 import android.content.Intent;
 import android.content.pm.PackageManager;
 import android.content.pm.ProviderInfo;
 import android.content.res.AssetFileDescriptor;
 import android.database.Cursor;
 import android.graphics.Bitmap;
 import android.graphics.BitmapFactory;
 import android.graphics.Point;
 import android.graphics.drawable.Drawable;
 import android.net.Uri;
 import android.os.Bundle;
 import android.os.Parcel;
 import android.os.ParcelFileDescriptor;
 import android.os.ParcelFileDescriptor.OnCloseListener;
 import android.os.Parcelable;
 import android.util.Log;

 import com.android.internal.util.Preconditions;
 import com.google.android.collect.Lists;

 import libcore.io.ErrnoException;
 import libcore.io.IoBridge;
 import libcore.io.IoUtils;
 import libcore.io.Libcore;

 import java.io.FileDescriptor;
 import java.io.IOException;
 import java.util.List;

 /**
  * Defines the contract between a documents provider and the platform.
  * <p>
  * To create a document provider, extend {@link DocumentsProvider}, which
  * provides a foundational implementation of this contract.
  *
  * @see DocumentsProvider
  */
 public final class DocumentsContract {
     private static final String TAG = "Documents";

     // content://com.example/docs/12/
     // content://com.example/docs/12/children/
     // content://com.example/docs/12/search/?query=pony

     private DocumentsContract() {
     }

     /** {@hide} */
     public static final String META_DATA_DOCUMENT_PROVIDER = "android.content.DOCUMENT_PROVIDER";

     /** {@hide} */
     public static final String ACTION_MANAGE_DOCUMENTS = "android.provider.action.MANAGE_DOCUMENTS";

     /** {@hide} */
     public static final String
             ACTION_DOCUMENT_ROOT_CHANGED = "android.provider.action.DOCUMENT_ROOT_CHANGED";

     /**
      * Constants for individual documents.
      */
     public final static class Documents {
         private Documents() {
         }

         /**
          * MIME type of a document which is a directory that may contain additional
          * documents.
          */
         public static final String MIME_TYPE_DIR = "vnd.android.doc/dir";

         /**
          * Flag indicating that a document is a directory that supports creation of
          * new files within it.
          *
          * @see DocumentColumns#FLAGS
          */
         public static final int FLAG_SUPPORTS_CREATE = 1;

         /**
          * Flag indicating that a document is renamable.
          *
          * @see DocumentColumns#FLAGS
          */
         public static final int FLAG_SUPPORTS_RENAME = 1 << 1;

         /**
          * Flag indicating that a document is deletable.
          *
          * @see DocumentColumns#FLAGS
          */
         public static final int FLAG_SUPPORTS_DELETE = 1 << 2;

         /**
          * Flag indicating that a document can be represented as a thumbnail.
          *
          * @see DocumentColumns#FLAGS
          */
         public static final int FLAG_SUPPORTS_THUMBNAIL = 1 << 3;

         /**
          * Flag indicating that a document is a directory that supports search.
          *
          * @see DocumentColumns#FLAGS
          */
         public static final int FLAG_SUPPORTS_SEARCH = 1 << 4;

         /**
          * Flag indicating that a document supports writing.
          *
          * @see DocumentColumns#FLAGS
          */
         public static final int FLAG_SUPPORTS_WRITE = 1 << 5;

         /**
          * Flag indicating that a document is a directory that prefers its contents
          * be shown in a larger format grid. Usually suitable when a directory
          * contains mostly pictures.
          *
          * @see DocumentColumns#FLAGS
          */
         public static final int FLAG_PREFERS_GRID = 1 << 6;
     }

     /**
      * Extra boolean flag included in a directory {@link Cursor#getExtras()}
      * indicating that a document provider is still loading data. For example, a
      * provider has returned some results, but is still waiting on an
      * outstanding network request.
      *
      * @see ContentResolver#notifyChange(Uri, android.database.ContentObserver,
      *      boolean)
      */
     public static final String EXTRA_LOADING = "loading";

     /**
      * Extra string included in a directory {@link Cursor#getExtras()}
      * providing an informational message that should be shown to a user. For
      * example, a provider may wish to indicate that not all documents are
      * available.
      */
     public static final String EXTRA_INFO = "info";

     /**
      * Extra string included in a directory {@link Cursor#getExtras()} providing
      * an error message that should be shown to a user. For example, a provider
      * may wish to indicate that a network error occurred. The user may choose
      * to retry, resulting in a new query.
      */
     public static final String EXTRA_ERROR = "error";

     /** {@hide} */
     public static final String METHOD_GET_ROOTS = "android:getRoots";
     /** {@hide} */
     public static final String METHOD_CREATE_DOCUMENT = "android:createDocument";
     /** {@hide} */
     public static final String METHOD_RENAME_DOCUMENT = "android:renameDocument";
     /** {@hide} */
     public static final String METHOD_DELETE_DOCUMENT = "android:deleteDocument";

     /** {@hide} */
     public static final String EXTRA_AUTHORITY = "authority";
     /** {@hide} */
     public static final String EXTRA_PACKAGE_NAME = "packageName";
     /** {@hide} */
     public static final String EXTRA_URI = "uri";
     /** {@hide} */
     public static final String EXTRA_ROOTS = "roots";
     /** {@hide} */
     public static final String EXTRA_THUMBNAIL_SIZE = "thumbnail_size";

     private static final String PATH_DOCS = "docs";
     private static final String PATH_CHILDREN = "children";
     private static final String PATH_SEARCH = "search";

     private static final String PARAM_QUERY = "query";

     /**
      * Build Uri representing the given {@link DocumentColumns#DOC_ID} in a
      * document provider.
      */
     public static Uri buildDocumentUri(String authority, String docId) {
         return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT)
                 .authority(authority).appendPath(PATH_DOCS).appendPath(docId).build();
     }

     /**
      * Build Uri representing the contents of the given directory in a document
      * provider. The given document must be {@link Documents#MIME_TYPE_DIR}.
      *
      * @hide
      */
     public static Uri buildChildrenUri(String authority, String docId) {
         return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT).authority(authority)
                 .appendPath(PATH_DOCS).appendPath(docId).appendPath(PATH_CHILDREN).build();
     }

     /**
      * Build Uri representing a search for matching documents under a specific
      * directory in a document provider. The given document must have
      * {@link Documents#FLAG_SUPPORTS_SEARCH}.
      *
      * @hide
      */
     public static Uri buildSearchUri(String authority, String docId, String query) {
         return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT).authority(authority)
                 .appendPath(PATH_DOCS).appendPath(docId).appendPath(PATH_SEARCH)
                 .appendQueryParameter(PARAM_QUERY, query).build();
     }

     /**
      * Extract the {@link DocumentColumns#DOC_ID} from the given Uri.
      */
     public static String getDocId(Uri documentUri) {
         final List<String> paths = documentUri.getPathSegments();
         if (paths.size() < 2) {
             throw new IllegalArgumentException("Not a document: " + documentUri);
         }
         if (!PATH_DOCS.equals(paths.get(0))) {
             throw new IllegalArgumentException("Not a document: " + documentUri);
         }
         return paths.get(1);
     }

     /** {@hide} */
     public static String getSearchQuery(Uri documentUri) {
         return documentUri.getQueryParameter(PARAM_QUERY);
     }

     /**
      * Standard columns for document queries. Document providers <em>must</em>
      * support at least these columns when queried.
      */
     public interface DocumentColumns extends OpenableColumns {
         /**
          * Unique ID for a document. Values <em>must</em> never change once
          * returned, since they may used for long-term Uri permission grants.
          * <p>
          * Type: STRING
          */
         public static final String DOC_ID = "doc_id";

         /**
          * MIME type of a document.
          * <p>
          * Type: STRING
          *
          * @see Documents#MIME_TYPE_DIR
          */
         public static final String MIME_TYPE = "mime_type";

         /**
          * Timestamp when a document was last modified, in milliseconds since
          * January 1, 1970 00:00:00.0 UTC, or {@code null} if unknown. Document
          * providers can update this field using events from
          * {@link OnCloseListener} or other reliable
          * {@link ParcelFileDescriptor} transports.
          * <p>
          * Type: INTEGER (long)
          *
          * @see System#currentTimeMillis()
          */
         public static final String LAST_MODIFIED = "last_modified";

         /**
          * Specific icon resource for a document, or {@code null} to resolve
          * default using {@link #MIME_TYPE}.
          * <p>
          * Type: INTEGER (int)
          */
         public static final String ICON = "icon";

         /**
          * Summary for a document, or {@code null} to omit.
          * <p>
          * Type: STRING
          */
         public static final String SUMMARY = "summary";

         /**
          * Flags that apply to a specific document.
          * <p>
          * Type: INTEGER (int)
          */
         public static final String FLAGS = "flags";
     }

     /**
      * Metadata about a specific root of documents.
      */
     public final static class DocumentRoot implements Parcelable {
         /**
          * Root that represents a storage service, such as a cloud-based
          * service.
          *
          * @see #rootType
          */
         public static final int ROOT_TYPE_SERVICE = 1;

         /**
          * Root that represents a shortcut to content that may be available
          * elsewhere through another storage root.
          *
          * @see #rootType
          */
         public static final int ROOT_TYPE_SHORTCUT = 2;

         /**
          * Root that represents a physical storage device.
          *
          * @see #rootType
          */
         public static final int ROOT_TYPE_DEVICE = 3;

         /**
          * Root that represents a physical storage device that should only be
          * displayed to advanced users.
          *
          * @see #rootType
          */
         public static final int ROOT_TYPE_DEVICE_ADVANCED = 4;

         /**
          * Flag indicating that at least one directory under this root supports
          * creating content.
          *
          * @see #flags
          */
         public static final int FLAG_SUPPORTS_CREATE = 1;

         /**
          * Flag indicating that this root offers content that is strictly local
          * on the device. That is, no network requests are made for the content.
          *
          * @see #flags
          */
         public static final int FLAG_LOCAL_ONLY = 1 << 1;

         /** {@hide} */
         public String authority;

         /**
          * Root type, use for clustering.
          *
          * @see #ROOT_TYPE_SERVICE
          * @see #ROOT_TYPE_DEVICE
          */
         public int rootType;

         /**
          * Flags for this root.
          *
          * @see #FLAG_LOCAL_ONLY
          */
         public int flags;

         /**
          * Icon resource ID for this root.
          */
         public int icon;

         /**
          * Title for this root.
          */
         public String title;

         /**
          * Summary for this root. May be {@code null}.
          */
         public String summary;

         /**
          * Document which is a directory that represents the top of this root.
          * Must not be {@code null}.
          *
          * @see DocumentColumns#DOC_ID
          */
         public String docId;

         /**
          * Document which is a directory representing recently modified
          * documents under this root. This directory should return at most two
          * dozen documents modified within the last 90 days. May be {@code null}
          * if this root doesn't support recents.
          *
          * @see DocumentColumns#DOC_ID
          */
         public String recentDocId;

         /**
          * Number of free bytes of available in this root, or -1 if unknown or
          * unbounded.
          */
         public long availableBytes;

         /**
          * Set of MIME type filters describing the content offered by this root,
          * or {@code null} to indicate that all MIME types are supported. For
          * example, a provider only supporting audio and video might set this to
          * {@code ["audio/*", "video/*"]}.
          */
         public String[] mimeTypes;

         public DocumentRoot() {
         }

         /** {@hide} */
         public DocumentRoot(Parcel in) {
             rootType = in.readInt();
             flags = in.readInt();
             icon = in.readInt();
             title = in.readString();
             summary = in.readString();
             docId = in.readString();
             recentDocId = in.readString();
             availableBytes = in.readLong();
             mimeTypes = in.readStringArray();
         }

         /** {@hide} */
         public Drawable loadIcon(Context context) {
             if (icon != 0) {
                 if (authority != null) {
                     final PackageManager pm = context.getPackageManager();
                     final ProviderInfo info = pm.resolveContentProvider(authority, 0);
                     if (info != null) {
                         return pm.getDrawable(info.packageName, icon, info.applicationInfo);
                     }
                 } else {
                     return context.getResources().getDrawable(icon);
                 }
             }
             return null;
         }

         @Override
         public int describeContents() {
             return 0;
         }

         @Override
         public void writeToParcel(Parcel dest, int flags) {
             Preconditions.checkNotNull(docId);

             dest.writeInt(rootType);
             dest.writeInt(flags);
             dest.writeInt(icon);
             dest.writeString(title);
             dest.writeString(summary);
             dest.writeString(docId);
             dest.writeString(recentDocId);
             dest.writeLong(availableBytes);
             dest.writeStringArray(mimeTypes);
         }

         public static final Creator<DocumentRoot> CREATOR = new Creator<DocumentRoot>() {
             @Override
             public DocumentRoot createFromParcel(Parcel in) {
                 return new DocumentRoot(in);
             }

             @Override
             public DocumentRoot[] newArray(int size) {
                 return new DocumentRoot[size];
             }
         };
     }

     /**
      * Return list of all documents that the calling package has "open." These
      * are Uris matching {@link DocumentsContract} to which persistent
      * read/write access has been granted, usually through
      * {@link Intent#ACTION_OPEN_DOCUMENT} or
      * {@link Intent#ACTION_CREATE_DOCUMENT}.
      *
      * @see Context#grantUriPermission(String, Uri, int)
      * @see ContentResolver#getIncomingUriPermissionGrants(int, int)
      */
     public static Uri[] getOpenDocuments(Context context) {
         final int openedFlags = Intent.FLAG_GRANT_READ_URI_PERMISSION
                 | Intent.FLAG_GRANT_WRITE_URI_PERMISSION | Intent.FLAG_PERSIST_GRANT_URI_PERMISSION;
         final Uri[] uris = context.getContentResolver()
                 .getIncomingUriPermissionGrants(openedFlags, openedFlags);

         // Filter to only include document providers
         final PackageManager pm = context.getPackageManager();
         final List<Uri> result = Lists.newArrayList();
         for (Uri uri : uris) {
             final ProviderInfo info = pm.resolveContentProvider(
                     uri.getAuthority(), PackageManager.GET_META_DATA);
             if (info.metaData.containsKey(META_DATA_DOCUMENT_PROVIDER)) {
                 result.add(uri);
             }
         }

         return result.toArray(new Uri[result.size()]);
     }

     /**
      * Return thumbnail representing the document at the given URI. Callers are
      * responsible for their own in-memory caching. Given document must have
      * {@link Documents#FLAG_SUPPORTS_THUMBNAIL} set.
      *
      * @return decoded thumbnail, or {@code null} if problem was encountered.
      * @hide
      */
     public static Bitmap getThumbnail(ContentResolver resolver, Uri documentUri, Point size) {
         final Bundle openOpts = new Bundle();
         openOpts.putParcelable(DocumentsContract.EXTRA_THUMBNAIL_SIZE, size);

         AssetFileDescriptor afd = null;
         try {
             afd = resolver.openTypedAssetFileDescriptor(documentUri, "image/*", openOpts);

             final FileDescriptor fd = afd.getFileDescriptor();
             final long offset = afd.getStartOffset();
             final long length = afd.getDeclaredLength();

             // Some thumbnails might be a region inside a larger file, such as
             // an EXIF thumbnail. Since BitmapFactory aggressively seeks around
             // the entire file, we read the region manually.
             byte[] region = null;
             if (offset > 0 && length <= 64 * KB_IN_BYTES) {
                 region = new byte[(int) length];
                 Libcore.os.lseek(fd, offset, SEEK_SET);
                 if (IoBridge.read(fd, region, 0, region.length) != region.length) {
                     region = null;
                 }
             }

             // We requested a rough thumbnail size, but the remote size may have
             // returned something giant, so defensively scale down as needed.
             final BitmapFactory.Options opts = new BitmapFactory.Options();
             opts.inJustDecodeBounds = true;
             if (region != null) {
                 BitmapFactory.decodeByteArray(region, 0, region.length, opts);
             } else {
                 BitmapFactory.decodeFileDescriptor(fd, null, opts);
             }

             final int widthSample = opts.outWidth / size.x;
             final int heightSample = opts.outHeight / size.y;

             opts.inJustDecodeBounds = false;
             opts.inSampleSize = Math.min(widthSample, heightSample);
             Log.d(TAG, "Decoding with sample size " + opts.inSampleSize);
             if (region != null) {
                 return BitmapFactory.decodeByteArray(region, 0, region.length, opts);
             } else {
                 return BitmapFactory.decodeFileDescriptor(fd, null, opts);
             }
         } catch (ErrnoException e) {
             Log.w(TAG, "Failed to load thumbnail for " + documentUri + ": " + e);
             return null;
         } catch (IOException e) {
             Log.w(TAG, "Failed to load thumbnail for " + documentUri + ": " + e);
             return null;
         } finally {
             IoUtils.closeQuietly(afd);
         }
     }

     /** {@hide} */
     public static List<DocumentRoot> getDocumentRoots(ContentProviderClient client) {
         try {
             final Bundle out = client.call(METHOD_GET_ROOTS, null, null);
             final List<DocumentRoot> roots = out.getParcelableArrayList(EXTRA_ROOTS);
             return roots;
         } catch (Exception e) {
             Log.w(TAG, "Failed to get roots", e);
             return null;
         }
     }

     /**
      * Create a new document under the given parent document with MIME type and
      * display name.
      *
      * @param docId document with {@link Documents#FLAG_SUPPORTS_CREATE}
      * @param mimeType MIME type of new document
      * @param displayName name of new document
      * @return newly created document, or {@code null} if failed
      * @hide
      */
     public static String createDocument(
             ContentProviderClient client, String docId, String mimeType, String displayName) {
         final Bundle in = new Bundle();
         in.putString(DocumentColumns.DOC_ID, docId);
         in.putString(DocumentColumns.MIME_TYPE, mimeType);
         in.putString(DocumentColumns.DISPLAY_NAME, displayName);

         try {
             final Bundle out = client.call(METHOD_CREATE_DOCUMENT, null, in);
             return out.getString(DocumentColumns.DOC_ID);
         } catch (Exception e) {
             Log.w(TAG, "Failed to create document", e);
             return null;
         }
     }

     /**
      * Rename the given document.
      *
      * @param docId document with {@link Documents#FLAG_SUPPORTS_RENAME}
      * @return document which may have changed due to rename, or {@code null} if
      *         rename failed.
      * @hide
      */
     public static String renameDocument(
             ContentProviderClient client, String docId, String displayName) {
         final Bundle in = new Bundle();
         in.putString(DocumentColumns.DOC_ID, docId);
         in.putString(DocumentColumns.DISPLAY_NAME, displayName);

         try {
             final Bundle out = client.call(METHOD_RENAME_DOCUMENT, null, in);
             return out.getString(DocumentColumns.DOC_ID);
         } catch (Exception e) {
             Log.w(TAG, "Failed to rename document", e);
             return null;
         }
     }

     /**
      * Delete the given document.
      *
      * @param docId document with {@link Documents#FLAG_SUPPORTS_DELETE}
      * @hide
      */
     public static boolean deleteDocument(ContentProviderClient client, String docId) {
         final Bundle in = new Bundle();
         in.putString(DocumentColumns.DOC_ID, docId);

         try {
             client.call(METHOD_DELETE_DOCUMENT, null, in);
             return true;
         } catch (Exception e) {
             Log.w(TAG, "Failed to delete document", e);
             return false;
         }
     }
 }
	/*
	* Copyright (C) 2013 The Android Open Source Project
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	package android.provider;

	import static android.net.TrafficStats.KB_IN_BYTES;
	import static libcore.io.OsConstants.SEEK_SET;

	import android.content.ContentProviderClient;
	import android.content.ContentResolver;
	import android.content.Context;
	import android.content.Intent;
	import android.content.pm.PackageManager;
	import android.content.pm.ProviderInfo;
	import android.content.res.AssetFileDescriptor;
	import android.database.Cursor;
	import android.graphics.Bitmap;
	import android.graphics.BitmapFactory;
	import android.graphics.Point;
	import android.graphics.drawable.Drawable;
	import android.net.Uri;
	import android.os.Bundle;
	import android.os.Parcel;
	import android.os.ParcelFileDescriptor;
	import android.os.ParcelFileDescriptor.OnCloseListener;
	import android.os.Parcelable;
	import android.util.Log;

	import com.android.internal.util.Preconditions;
	import com.google.android.collect.Lists;

	import libcore.io.ErrnoException;
	import libcore.io.IoBridge;
	import libcore.io.IoUtils;
	import libcore.io.Libcore;

	import java.io.FileDescriptor;
	import java.io.IOException;
	import java.util.List;

	/**
	* Defines the contract between a documents provider and the platform.
	* <p>
	* To create a document provider, extend {@link DocumentsProvider}, which
	* provides a foundational implementation of this contract.
	*
	* @see DocumentsProvider
	*/
	public final class DocumentsContract {
	private static final String TAG = "Documents";

	// content://com.example/docs/12/
	// content://com.example/docs/12/children/
	// content://com.example/docs/12/search/?query=pony

	private DocumentsContract() {
	}

	/** {@hide} */
	public static final String META_DATA_DOCUMENT_PROVIDER = "android.content.DOCUMENT_PROVIDER";

	/** {@hide} */
	public static final String ACTION_MANAGE_DOCUMENTS = "android.provider.action.MANAGE_DOCUMENTS";

	/** {@hide} */
	public static final String
	ACTION_DOCUMENT_ROOT_CHANGED = "android.provider.action.DOCUMENT_ROOT_CHANGED";

	/**
	* Constants for individual documents.
	*/
	public final static class Documents {
	private Documents() {
	}

	/**
	* MIME type of a document which is a directory that may contain additional
	* documents.
	*/
	public static final String MIME_TYPE_DIR = "vnd.android.doc/dir";

	/**
	* Flag indicating that a document is a directory that supports creation of
	* new files within it.
	*
	* @see DocumentColumns#FLAGS
	*/
	public static final int FLAG_SUPPORTS_CREATE = 1;

	/**
	* Flag indicating that a document is renamable.
	*
	* @see DocumentColumns#FLAGS
	*/
	public static final int FLAG_SUPPORTS_RENAME = 1 << 1;

	/**
	* Flag indicating that a document is deletable.
	*
	* @see DocumentColumns#FLAGS
	*/
	public static final int FLAG_SUPPORTS_DELETE = 1 << 2;

	/**
	* Flag indicating that a document can be represented as a thumbnail.
	*
	* @see DocumentColumns#FLAGS
	*/
	public static final int FLAG_SUPPORTS_THUMBNAIL = 1 << 3;

	/**
	* Flag indicating that a document is a directory that supports search.
	*
	* @see DocumentColumns#FLAGS
	*/
	public static final int FLAG_SUPPORTS_SEARCH = 1 << 4;

	/**
	* Flag indicating that a document supports writing.
	*
	* @see DocumentColumns#FLAGS
	*/
	public static final int FLAG_SUPPORTS_WRITE = 1 << 5;

	/**
	* Flag indicating that a document is a directory that prefers its contents
	* be shown in a larger format grid. Usually suitable when a directory
	* contains mostly pictures.
	*
	* @see DocumentColumns#FLAGS
	*/
	public static final int FLAG_PREFERS_GRID = 1 << 6;
	}

	/**
	* Extra boolean flag included in a directory {@link Cursor#getExtras()}
	* indicating that a document provider is still loading data. For example, a
	* provider has returned some results, but is still waiting on an
	* outstanding network request.
	*
	* @see ContentResolver#notifyChange(Uri, android.database.ContentObserver,
	* boolean)
	*/
	public static final String EXTRA_LOADING = "loading";

	/**
	* Extra string included in a directory {@link Cursor#getExtras()}
	* providing an informational message that should be shown to a user. For
	* example, a provider may wish to indicate that not all documents are
	* available.
	*/
	public static final String EXTRA_INFO = "info";

	/**
	* Extra string included in a directory {@link Cursor#getExtras()} providing
	* an error message that should be shown to a user. For example, a provider
	* may wish to indicate that a network error occurred. The user may choose
	* to retry, resulting in a new query.
	*/
	public static final String EXTRA_ERROR = "error";

	/** {@hide} */
	public static final String METHOD_GET_ROOTS = "android:getRoots";
	/** {@hide} */
	public static final String METHOD_CREATE_DOCUMENT = "android:createDocument";
	/** {@hide} */
	public static final String METHOD_RENAME_DOCUMENT = "android:renameDocument";
	/** {@hide} */
	public static final String METHOD_DELETE_DOCUMENT = "android:deleteDocument";

	/** {@hide} */
	public static final String EXTRA_AUTHORITY = "authority";
	/** {@hide} */
	public static final String EXTRA_PACKAGE_NAME = "packageName";
	/** {@hide} */
	public static final String EXTRA_URI = "uri";
	/** {@hide} */
	public static final String EXTRA_ROOTS = "roots";
	/** {@hide} */
	public static final String EXTRA_THUMBNAIL_SIZE = "thumbnail_size";

	private static final String PATH_DOCS = "docs";
	private static final String PATH_CHILDREN = "children";
	private static final String PATH_SEARCH = "search";

	private static final String PARAM_QUERY = "query";

	/**
	* Build Uri representing the given {@link DocumentColumns#DOC_ID} in a
	* document provider.
	*/
	public static Uri buildDocumentUri(String authority, String docId) {
	return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT)
	.authority(authority).appendPath(PATH_DOCS).appendPath(docId).build();
	}

	/**
	* Build Uri representing the contents of the given directory in a document
	* provider. The given document must be {@link Documents#MIME_TYPE_DIR}.
	*
	* @hide
	*/
	public static Uri buildChildrenUri(String authority, String docId) {
	return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT).authority(authority)
	.appendPath(PATH_DOCS).appendPath(docId).appendPath(PATH_CHILDREN).build();
	}

	/**
	* Build Uri representing a search for matching documents under a specific
	* directory in a document provider. The given document must have
	* {@link Documents#FLAG_SUPPORTS_SEARCH}.
	*
	* @hide
	*/
	public static Uri buildSearchUri(String authority, String docId, String query) {
	return new Uri.Builder().scheme(ContentResolver.SCHEME_CONTENT).authority(authority)
	.appendPath(PATH_DOCS).appendPath(docId).appendPath(PATH_SEARCH)
	.appendQueryParameter(PARAM_QUERY, query).build();
	}

	/**
	* Extract the {@link DocumentColumns#DOC_ID} from the given Uri.
	*/
	public static String getDocId(Uri documentUri) {
	final List<String> paths = documentUri.getPathSegments();
	if (paths.size() < 2) {
	throw new IllegalArgumentException("Not a document: " + documentUri);
	}
	if (!PATH_DOCS.equals(paths.get(0))) {
	throw new IllegalArgumentException("Not a document: " + documentUri);
	}
	return paths.get(1);
	}

	/** {@hide} */
	public static String getSearchQuery(Uri documentUri) {
	return documentUri.getQueryParameter(PARAM_QUERY);
	}

	/**
	* Standard columns for document queries. Document providers <em>must</em>
	* support at least these columns when queried.
	*/
	public interface DocumentColumns extends OpenableColumns {
	/**
	* Unique ID for a document. Values <em>must</em> never change once
	* returned, since they may used for long-term Uri permission grants.
	* <p>
	* Type: STRING
	*/
	public static final String DOC_ID = "doc_id";

	/**
	* MIME type of a document.
	* <p>
	* Type: STRING
	*
	* @see Documents#MIME_TYPE_DIR
	*/
	public static final String MIME_TYPE = "mime_type";

	/**
	* Timestamp when a document was last modified, in milliseconds since
	* January 1, 1970 00:00:00.0 UTC, or {@code null} if unknown. Document
	* providers can update this field using events from
	* {@link OnCloseListener} or other reliable
	* {@link ParcelFileDescriptor} transports.
	* <p>
	* Type: INTEGER (long)
	*
	* @see System#currentTimeMillis()
	*/
	public static final String LAST_MODIFIED = "last_modified";

	/**
	* Specific icon resource for a document, or {@code null} to resolve
	* default using {@link #MIME_TYPE}.
	* <p>
	* Type: INTEGER (int)
	*/
	public static final String ICON = "icon";

	/**
	* Summary for a document, or {@code null} to omit.
	* <p>
	* Type: STRING
	*/
	public static final String SUMMARY = "summary";

	/**
	* Flags that apply to a specific document.
	* <p>
	* Type: INTEGER (int)
	*/
	public static final String FLAGS = "flags";
	}

	/**
	* Metadata about a specific root of documents.
	*/
	public final static class DocumentRoot implements Parcelable {
	/**
	* Root that represents a storage service, such as a cloud-based
	* service.
	*
	* @see #rootType
	*/
	public static final int ROOT_TYPE_SERVICE = 1;

	/**
	* Root that represents a shortcut to content that may be available
	* elsewhere through another storage root.
	*
	* @see #rootType
	*/
	public static final int ROOT_TYPE_SHORTCUT = 2;

	/**
	* Root that represents a physical storage device.
	*
	* @see #rootType
	*/
	public static final int ROOT_TYPE_DEVICE = 3;

	/**
	* Root that represents a physical storage device that should only be
	* displayed to advanced users.
	*
	* @see #rootType
	*/
	public static final int ROOT_TYPE_DEVICE_ADVANCED = 4;

	/**
	* Flag indicating that at least one directory under this root supports
	* creating content.
	*
	* @see #flags
	*/
	public static final int FLAG_SUPPORTS_CREATE = 1;

	/**
	* Flag indicating that this root offers content that is strictly local
	* on the device. That is, no network requests are made for the content.
	*
	* @see #flags
	*/
	public static final int FLAG_LOCAL_ONLY = 1 << 1;

	/** {@hide} */
	public String authority;

	/**
	* Root type, use for clustering.
	*
	* @see #ROOT_TYPE_SERVICE
	* @see #ROOT_TYPE_DEVICE
	*/
	public int rootType;

	/**
	* Flags for this root.
	*
	* @see #FLAG_LOCAL_ONLY
	*/
	public int flags;

	/**
	* Icon resource ID for this root.
	*/
	public int icon;

	/**
	* Title for this root.
	*/
	public String title;

	/**
	* Summary for this root. May be {@code null}.
	*/
	public String summary;

	/**
	* Document which is a directory that represents the top of this root.
	* Must not be {@code null}.
	*
	* @see DocumentColumns#DOC_ID
	*/
	public String docId;

	/**
	* Document which is a directory representing recently modified
	* documents under this root. This directory should return at most two
	* dozen documents modified within the last 90 days. May be {@code null}
	* if this root doesn't support recents.
	*
	* @see DocumentColumns#DOC_ID
	*/
	public String recentDocId;

	/**
	* Number of free bytes of available in this root, or -1 if unknown or
	* unbounded.
	*/
	public long availableBytes;

	/**
	* Set of MIME type filters describing the content offered by this root,
	* or {@code null} to indicate that all MIME types are supported. For
	* example, a provider only supporting audio and video might set this to
	* {@code ["audio/", "video/"]}.
	*/
	public String[] mimeTypes;

	public DocumentRoot() {
	}

	/** {@hide} */
	public DocumentRoot(Parcel in) {
	rootType = in.readInt();
	flags = in.readInt();
	icon = in.readInt();
	title = in.readString();
	summary = in.readString();
	docId = in.readString();
	recentDocId = in.readString();
	availableBytes = in.readLong();
	mimeTypes = in.readStringArray();
	}

	/** {@hide} */
	public Drawable loadIcon(Context context) {
	if (icon != 0) {
	if (authority != null) {
	final PackageManager pm = context.getPackageManager();
	final ProviderInfo info = pm.resolveContentProvider(authority, 0);
	if (info != null) {
	return pm.getDrawable(info.packageName, icon, info.applicationInfo);
	}
	} else {
	return context.getResources().getDrawable(icon);
	}
	}
	return null;
	}

	@Override
	public int describeContents() {
	return 0;
	}

	@Override
	public void writeToParcel(Parcel dest, int flags) {
	Preconditions.checkNotNull(docId);

	dest.writeInt(rootType);
	dest.writeInt(flags);
	dest.writeInt(icon);
	dest.writeString(title);
	dest.writeString(summary);
	dest.writeString(docId);
	dest.writeString(recentDocId);
	dest.writeLong(availableBytes);
	dest.writeStringArray(mimeTypes);
	}

	public static final Creator<DocumentRoot> CREATOR = new Creator<DocumentRoot>() {
	@Override
	public DocumentRoot createFromParcel(Parcel in) {
	return new DocumentRoot(in);
	}

	@Override
	public DocumentRoot[] newArray(int size) {
	return new DocumentRoot[size];
	}
	};
	}

	/**
	* Return list of all documents that the calling package has "open." These
	* are Uris matching {@link DocumentsContract} to which persistent
	* read/write access has been granted, usually through
	* {@link Intent#ACTION_OPEN_DOCUMENT} or
	* {@link Intent#ACTION_CREATE_DOCUMENT}.
	*
	* @see Context#grantUriPermission(String, Uri, int)
	* @see ContentResolver#getIncomingUriPermissionGrants(int, int)
	*/
	public static Uri[] getOpenDocuments(Context context) {
	final int openedFlags = Intent.FLAG_GRANT_READ_URI_PERMISSION
	\| Intent.FLAG_GRANT_WRITE_URI_PERMISSION \| Intent.FLAG_PERSIST_GRANT_URI_PERMISSION;
	final Uri[] uris = context.getContentResolver()
	.getIncomingUriPermissionGrants(openedFlags, openedFlags);

	// Filter to only include document providers
	final PackageManager pm = context.getPackageManager();
	final List<Uri> result = Lists.newArrayList();
	for (Uri uri : uris) {
	final ProviderInfo info = pm.resolveContentProvider(
	uri.getAuthority(), PackageManager.GET_META_DATA);
	if (info.metaData.containsKey(META_DATA_DOCUMENT_PROVIDER)) {
	result.add(uri);
	}
	}

	return result.toArray(new Uri[result.size()]);
	}

	/**
	* Return thumbnail representing the document at the given URI. Callers are
	* responsible for their own in-memory caching. Given document must have
	* {@link Documents#FLAG_SUPPORTS_THUMBNAIL} set.
	*
	* @return decoded thumbnail, or {@code null} if problem was encountered.
	* @hide
	*/
	public static Bitmap getThumbnail(ContentResolver resolver, Uri documentUri, Point size) {
	final Bundle openOpts = new Bundle();
	openOpts.putParcelable(DocumentsContract.EXTRA_THUMBNAIL_SIZE, size);

	AssetFileDescriptor afd = null;
	try {
	afd = resolver.openTypedAssetFileDescriptor(documentUri, "image/*", openOpts);

	final FileDescriptor fd = afd.getFileDescriptor();
	final long offset = afd.getStartOffset();
	final long length = afd.getDeclaredLength();

	// Some thumbnails might be a region inside a larger file, such as
	// an EXIF thumbnail. Since BitmapFactory aggressively seeks around
	// the entire file, we read the region manually.
	byte[] region = null;
	if (offset > 0 && length <= 64 * KB_IN_BYTES) {
	region = new byte[(int) length];
	Libcore.os.lseek(fd, offset, SEEK_SET);
	if (IoBridge.read(fd, region, 0, region.length) != region.length) {
	region = null;
	}
	}

	// We requested a rough thumbnail size, but the remote size may have
	// returned something giant, so defensively scale down as needed.
	final BitmapFactory.Options opts = new BitmapFactory.Options();
	opts.inJustDecodeBounds = true;
	if (region != null) {
	BitmapFactory.decodeByteArray(region, 0, region.length, opts);
	} else {
	BitmapFactory.decodeFileDescriptor(fd, null, opts);
	}

	final int widthSample = opts.outWidth / size.x;
	final int heightSample = opts.outHeight / size.y;

	opts.inJustDecodeBounds = false;
	opts.inSampleSize = Math.min(widthSample, heightSample);
	Log.d(TAG, "Decoding with sample size " + opts.inSampleSize);
	if (region != null) {
	return BitmapFactory.decodeByteArray(region, 0, region.length, opts);
	} else {
	return BitmapFactory.decodeFileDescriptor(fd, null, opts);
	}
	} catch (ErrnoException e) {
	Log.w(TAG, "Failed to load thumbnail for " + documentUri + ": " + e);
	return null;
	} catch (IOException e) {
	Log.w(TAG, "Failed to load thumbnail for " + documentUri + ": " + e);
	return null;
	} finally {
	IoUtils.closeQuietly(afd);
	}
	}

	/** {@hide} */
	public static List<DocumentRoot> getDocumentRoots(ContentProviderClient client) {
	try {
	final Bundle out = client.call(METHOD_GET_ROOTS, null, null);
	final List<DocumentRoot> roots = out.getParcelableArrayList(EXTRA_ROOTS);
	return roots;
	} catch (Exception e) {
	Log.w(TAG, "Failed to get roots", e);
	return null;
	}
	}

	/**
	* Create a new document under the given parent document with MIME type and
	* display name.
	*
	* @param docId document with {@link Documents#FLAG_SUPPORTS_CREATE}
	* @param mimeType MIME type of new document
	* @param displayName name of new document
	* @return newly created document, or {@code null} if failed
	* @hide
	*/
	public static String createDocument(
	ContentProviderClient client, String docId, String mimeType, String displayName) {
	final Bundle in = new Bundle();
	in.putString(DocumentColumns.DOC_ID, docId);
	in.putString(DocumentColumns.MIME_TYPE, mimeType);
	in.putString(DocumentColumns.DISPLAY_NAME, displayName);

	try {
	final Bundle out = client.call(METHOD_CREATE_DOCUMENT, null, in);
	return out.getString(DocumentColumns.DOC_ID);
	} catch (Exception e) {
	Log.w(TAG, "Failed to create document", e);
	return null;
	}
	}

	/**
	* Rename the given document.
	*
	* @param docId document with {@link Documents#FLAG_SUPPORTS_RENAME}
	* @return document which may have changed due to rename, or {@code null} if
	* rename failed.
	* @hide
	*/
	public static String renameDocument(
	ContentProviderClient client, String docId, String displayName) {
	final Bundle in = new Bundle();
	in.putString(DocumentColumns.DOC_ID, docId);
	in.putString(DocumentColumns.DISPLAY_NAME, displayName);

	try {
	final Bundle out = client.call(METHOD_RENAME_DOCUMENT, null, in);
	return out.getString(DocumentColumns.DOC_ID);
	} catch (Exception e) {
	Log.w(TAG, "Failed to rename document", e);
	return null;
	}
	}

	/**
	* Delete the given document.
	*
	* @param docId document with {@link Documents#FLAG_SUPPORTS_DELETE}
	* @hide
	*/
	public static boolean deleteDocument(ContentProviderClient client, String docId) {
	final Bundle in = new Bundle();
	in.putString(DocumentColumns.DOC_ID, docId);

	try {
	client.call(METHOD_DELETE_DOCUMENT, null, in);
	return true;
	} catch (Exception e) {
	Log.w(TAG, "Failed to delete document", e);
	return false;
	}
	}
	}