1 /* 2 * Copyright (C) 2013 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.android.photos.data; 18 19 import android.net.Uri; 20 21 import java.io.File; 22 23 public interface MediaRetriever { 24 public enum MediaSize { 25 TemporaryThumbnail(5), Thumbnail(10), TemporaryPreview(15), Preview(20), Original(30); 26 27 private final int mValue; 28 MediaSize(int value)29 private MediaSize(int value) { 30 mValue = value; 31 } 32 getValue()33 public int getValue() { 34 return mValue; 35 } 36 fromInteger(int value)37 static MediaSize fromInteger(int value) { 38 switch (value) { 39 case 10: 40 return MediaSize.Thumbnail; 41 case 20: 42 return MediaSize.Preview; 43 case 30: 44 return MediaSize.Original; 45 default: 46 throw new IllegalArgumentException(); 47 } 48 } 49 isBetterThan(MediaSize that)50 public boolean isBetterThan(MediaSize that) { 51 return mValue > that.mValue; 52 } 53 isTemporary()54 public boolean isTemporary() { 55 return this == TemporaryThumbnail || this == TemporaryPreview; 56 } 57 } 58 59 /** 60 * Returns the local File for the given Uri. If the image is not stored 61 * locally, null should be returned. The image should not be retrieved if it 62 * isn't already available. 63 * 64 * @param contentUri The media URI to search for. 65 * @return The local File of the image if it is available or null if it 66 * isn't. 67 */ getLocalFile(Uri contentUri)68 File getLocalFile(Uri contentUri); 69 70 /** 71 * Returns the fast access image type for a given image size, if supported. 72 * This image should be smaller than size and should be quick to retrieve. 73 * It does not have to obey the expected aspect ratio. 74 * 75 * @param contentUri The original media Uri. 76 * @param size The target size to search for a fast-access image. 77 * @return The fast image type supported for the given image size or null of 78 * no fast image is supported. 79 */ getFastImageSize(Uri contentUri, MediaSize size)80 MediaSize getFastImageSize(Uri contentUri, MediaSize size); 81 82 /** 83 * Returns a byte array containing the contents of the fast temporary image 84 * for a given image size. For example, a thumbnail may be smaller or of a 85 * different aspect ratio than the generated thumbnail. 86 * 87 * @param contentUri The original media Uri. 88 * @param temporarySize The target media size. Guaranteed to be a MediaSize 89 * for which isTemporary() returns true. 90 * @return A byte array of contents for for the given contentUri and 91 * fastImageType. null can be retrieved if the quick retrieval 92 * fails. 93 */ getTemporaryImage(Uri contentUri, MediaSize temporarySize)94 byte[] getTemporaryImage(Uri contentUri, MediaSize temporarySize); 95 96 /** 97 * Retrieves an image and saves it to a file. 98 * 99 * @param contentUri The original media Uri. 100 * @param size The target media size. 101 * @param tempFile The file to write the bitmap to. 102 * @return <code>true</code> on success. 103 */ getMedia(Uri contentUri, MediaSize imageSize, File tempFile)104 boolean getMedia(Uri contentUri, MediaSize imageSize, File tempFile); 105 106 /** 107 * Normalizes a URI that may have additional parameters. It is fine to 108 * return contentUri. This is executed on the calling thread, so it must be 109 * a fast access operation and cannot depend, for example, on I/O. 110 * 111 * @param contentUri The URI to normalize 112 * @param size The size of the image being requested 113 * @return The normalized URI representation of contentUri. 114 */ normalizeUri(Uri contentUri, MediaSize size)115 Uri normalizeUri(Uri contentUri, MediaSize size); 116 117 /** 118 * Normalize the MediaSize for a given URI. Typically the size returned 119 * would be the passed-in size. Some URIs may only have one size used and 120 * should be treaded as Thumbnails, for example. This is executed on the 121 * calling thread, so it must be a fast access operation and cannot depend, 122 * for example, on I/O. 123 * 124 * @param contentUri The URI for the size being normalized. 125 * @param size The size to be normalized. 126 * @return The normalized size of the given URI. 127 */ normalizeMediaSize(Uri contentUri, MediaSize size)128 MediaSize normalizeMediaSize(Uri contentUri, MediaSize size); 129 } 130